home *** CD-ROM | disk | FTP | other *** search
/ The Utilities Experience / The Utilities Experience - Volume 1.iso / software / comms / ncp / docs / amigancp.doc next >
Text File  |  1994-10-19  |  56KB  |  1,784 lines
  1.  
  2.  
  3. AmigaNCP
  4. ********
  5.  
  6. Welcome to the AmigaNCP package, the AmigaOS implementation of
  7. Psion's NCP network protocol.
  8.  
  9. Copyright
  10. *********
  11.  
  12. This is a limited demonstration copy of the AmigaNCP package.  You
  13. may test it for up to 30 days.  If you like it, fill in the order form
  14. and send it to
  15.  
  16.      B&B Computersysteme
  17.      c/o Michael Balzer
  18.      Winchenbachstraße 12h
  19.      42281 Wuppertal
  20.      Germany
  21.  
  22. Payment may only be included cash or in form of a properly filled in
  23. euro cheque (with DM as currency).
  24.  
  25. In reply we will send you the full version and - if ordered - a printed
  26. manual.
  27.  
  28. The AmigaNCP package has been written by
  29.  
  30.      Oliver Wagner
  31.      o.wagner@pluribus.wupper.de
  32.      Winchenbachstraße 12h
  33.      42281 Wuppertal
  34.      Germany
  35.  
  36. ...who does this job for a living with his wife, four kids and two
  37. cats...
  38.  
  39. The AmigaNCP driver library, the AmigaNCP File Server, the AmigaNCP
  40. File System, the AmigaNCP Documentation and all associated files are
  41. copyright (C) 1994 Oliver Wagner, All Rights Reserved.
  42.  
  43.     Psion, the Psion Logo, Psion Series 3, 3-Link, Psion HC,
  44. Psion MC, SSD and Solid State Disk are registered Trademarks of
  45. Psion PLC.
  46.  
  47.     Amiga, the Amiga logo and AmigaDOS are registered Trademarks of
  48. Commodore-Amiga, Inc.
  49.  
  50. The author wishes to thank the following people for their help during
  51. AmigaNCP development:
  52.  
  53. David Wood of Psion Ltd.
  54.      Who provided the necessary information about the NCP protocol and
  55.      helped with beta testing the package
  56.  
  57. Jeremy "Jezar" Wakefield of Psion Ltd.
  58.      Who helped to track down several hidden and esoteric bugs.
  59.  
  60. Michael Balzer
  61.      Who crossread and corrected this manual.
  62.  
  63. Sandro Paolini
  64.      For his overall help on AmigaNCP development and testing.
  65.  
  66. Introduction
  67. ************
  68.  
  69. Overview
  70. ========
  71.  
  72. Psion's fine palmtop computer series, namely the S3 and S3a,
  73. contain an even finer operating system, whose neat features cover a full
  74. fledged peer-to-peer networking software using a protocol called
  75. NCP.
  76.  
  77. Using NCP, you can link together two Psion computers or a Psion and a
  78. different, perhaps stationary machine and happily exchange data on your
  79. behalf.  NCP services include, but are not limited to, accessing files
  80. on the remote machines as if they were on yours, in both directions.
  81.  
  82. Linking your palmtop to your stationary machine is generally quite a
  83. good idea.  Doing so via the NCP protocol requires your stationary
  84. machine to have an implemention of this protocol.  There have only been
  85. implementations for MS-DOS clones (the MCLINK.EXE shell), for Apple
  86. MacIntosh and for Acorn Archimedes - until now.
  87.  
  88. AmigaNCP features a full NCP implementation including a remote file
  89. server to access Amiga files from your Psion and a file system to access
  90. Psion files from your Amiga.  The package also offers an API to allow
  91. custom applications to directly access network services at the NCP
  92. level.
  93.  
  94. Parts of AmigaNCP
  95. =================
  96.  
  97. AmigaNCP actually consists of several different programs.
  98.  
  99. The main part is the ncp.library.  It contains the basic network
  100. services for exchanging data between two machines via a serial
  101. connection.  The protocol provides up to 8 data channels, which can be
  102. either passive (awaiting a connection from a client process) or active
  103. (attempting to connect to a server process).  One of the channels is
  104. reserved for the network supervisor application LINK.  The LINK
  105. functionality also has been integrated into ncp.library.
  106.  
  107. Besides network I/O functions, the library also provides several
  108. utility functions to deal with Psion text format and the Intel byte
  109. ordering.
  110.  
  111. The AmigaNCP-FileServer is an application built on top of
  112. ncp.library.  It provides a means of accessing AmigaDOS files
  113. from the remote Psion computer via the REM:: file system.  This
  114. allows you to access Amiga files just as if they were local Psion
  115. files.  With the Psion S3a, it allows you to use the Backup option to
  116. backup vital data files on your Amiga's harddisk.
  117.  
  118. The AmigaNCP-FileSystem uses the ncp.library to connect to the
  119. file server running on your Psion in order to provide access to Psion
  120. files from the AmigaDOS environment.  It provides a new AmigaDOS device
  121. named NCP: which offers access to all available Psion devices.  The
  122. Psion devices will be mounted as subdirectories in the NCP: window.
  123.  
  124. The AmigaNCP-Monitor monitors the activity of the NCP supervisor and
  125. gives detailed statistics about all channels.  This is an invaluable
  126. aid for debugging NCP applications.
  127.  
  128. The S3PrintServer allows you to print from your S3 or S3a directly to
  129. a printer connected to the Amiga.
  130.  
  131. The S3Run program remotely launches programs or applications on your
  132. Psion.
  133.  
  134. Using AmigaNCP
  135. **************
  136.  
  137. Installation
  138. ============
  139.  
  140. For using AmigaNCP you'll need...
  141.  
  142.   1. any Amiga equipped with OS 2.04 or better and a free serial port
  143.  
  144.   2. the IBM-PC version of the 3-Link serial cable
  145.  
  146.   3. and a Psion S3 or S3a (or any other model featuring Remote
  147.      Link)(1).
  148.  
  149.  
  150. To support Amiga systems without a hard disk, the AmigaNCP distribution
  151. has been organized to be ready-to-use.
  152.  
  153. Hard disk installation of AmigaNCP is best done using the provided
  154. Installer script.  The script will (by default) copy ncp.library to
  155. LIBS:, put the language catalogs into LOCALE:Catalogs/ and create an
  156. AmigaNCP drawer on your work partition.  The drawer will contain the
  157. network services, documentation and the NCP tools.  There's an
  158. additional option for installing the ncp.library developer material.
  159.  
  160. When installing the package for the first time, the installation
  161. procedure will ask you about the Psion model you're going to connect
  162. to.  The serial line speed will be set to the model's maximum (that is
  163. 9600 baud for the S3 or HC and 19200 baud for S3a or MC).
  164.  
  165. Configuring ncp.library
  166. =======================
  167.  
  168. The default serial configuration is to use the serial.device, unit 0,
  169. at 9600 baud(2).
  170.  
  171. You can overwrite these default parameters by setting or changing the
  172. environment variable NCP.config.  The environment variable will be
  173. read by the ncp.library each time a serial connection has to be
  174. established.
  175.  
  176. The parameter parsing is done just like in a shell command line; the
  177. template is D=DEVICE/K, U=UNIT/K/N, B=BAUD/K/N, NOREQ/S.  All
  178. parameters are optional, those not given will retain their default
  179. values.
  180.  
  181. An example:  To make AmigaNCP use duart.device, unit 1 at 19200 baud
  182. you have to set ENV:NCP.config to
  183.  
  184.     DEVICE=duart.device UNIT=1 BAUD=19200
  185.  
  186. The installation script will create both ENV:NCP.config and
  187. ENVARC:NCP.config with either
  188.  
  189.     DEVICE=serial.device UNIT=0 BAUD=9600
  190.  
  191. or
  192.  
  193.     DEVICE=serial.device UNIT=0 BAUD=19200
  194.  
  195. depending on your choice of Psion model.  Please note, that you may
  196. actually use any baud rate supported by the serial port in question
  197. (and of course supported by the other side's serial interface as well).
  198.  
  199. If you set the NOREQ switch, the library will not display any error
  200. requesters.
  201.  
  202. Note that you have to configure the remote site as well.  On the Psion
  203. S3 or S3a this consists of turning on NCP via the Remote Link menu of
  204. the system screen.  The baud rate must of course be set to the same
  205. value as used in ENV:NCP.config, or to 9600 if no configuration file
  206. exists.
  207.  
  208. Starting AmigaNCP
  209. =================
  210.  
  211. You don't start ncp.library directly.  Instead you start one or more
  212. of the AmigaNCP applications, which in turn will open the library and
  213. try to establish their connections to the remote NCP site.
  214.  
  215. The library automatically terminates a connection about 10 seconds
  216. after the last application has closed its network channels.
  217.  
  218. Note that the underlying serial device is free to be used by any other
  219. application as long as no NCP connection is active and no connection
  220. attempt is made.
  221.  
  222. NCP Requesters
  223. ==============
  224.  
  225. The ncp.library will put up error requesters if the network link
  226. breaks (and the NOREQ switch hasn't been set, see above).  The
  227. following table shows possible error conditions:
  228.  
  229. Can't open serial device
  230.      The device specified in ENV:NCP.config could not be opened.
  231.      Either the device does not exist (perhaps just because you
  232.      misspelled the device name) or it is in use by another process.
  233.  
  234. Timeout waiting for response
  235.      The serial device opened ok but the other side is not responding
  236.      to our handshake packet.  Most likey there is no Psion connected,
  237.      or it has it's Remote Link turned off.  This requester will
  238.      constantly show up if the AmigaNCP file system is running and the
  239.      serial link broke down.
  240.  
  241. Data not acknowledged
  242.      The last data packet has not been acknowledged.  This normally
  243.      denotes an NCP connection which has been interrupted during data
  244.      transfer.
  245.  
  246. Connection dropped
  247.      The remote side dropped the connection.
  248.  
  249. Argument error
  250.      Bad LLMAC request arguments.  You normally should not see this
  251.      error, it denotes an internal failure in the ncp.library high
  252.      level I/O functions.
  253.  
  254. Not connected
  255.      There is no LLMAC connection.  You normally should not see this
  256.      error, it denotes an internal failure in the ncp.library high
  257.      level I/O functions.
  258.  
  259. ---------- Footnotes ----------
  260.  
  261. (1)  In fact of course any NCP implementation does.  You can use
  262. AmigaNCP to connect to an NCP server running on an IBM PC or Apple Mac,
  263. or even to another AmigaNCP running on a different Amiga.
  264.  
  265. (2)  All other serial flags are fixed to 8N1, highspeed mode and 7-wire
  266. RTS/CTS handshake since this is required by the NCP protocol.
  267.  
  268. AmigaNCP File Server
  269. ********************
  270.  
  271. Introducing the File Server
  272. ===========================
  273.  
  274. The AmigaNCP File Server is an NCP application which provides access
  275. to Amiga files from the remote machine.  On startup it creates a
  276. passive NCP channel awaiting a connection from a remote file system.
  277.  
  278. On the S3 and S3a, the remote file system is built into the ROM.  It
  279. automatically attempts to connect to the remote file server when an NCP
  280. connection is made, and presents a new filesystem node named REM::,
  281. which in turn contains all the Amiga devices.  You can navigate through
  282. the Amiga devices via the system screen or directly access a file by
  283. it's full path name.
  284.  
  285. The Psion's file system was designed to be device independant, so there
  286. are no restrictions concerning the length of file names or extensions:
  287. The complete Amiga device, directory and file names are fully
  288. preserved.  However, directories are separated in the standard Psion
  289. manner via the \ character.
  290.  
  291. An example:  To access the Amiga file HD1:Test/Test.txt from the
  292. Psion, use the file name REM::HD1:\\TEST\\TEST.TXT.  To access
  293. SYS:S/Startup-Sequence, use REM::\\SYS:\\STARTUP-SEQUENCE.
  294.  
  295. When asked for a device list, the AmigaNCP File Server will output only
  296. real file system devices(1).  However, you may in fact access any
  297. AmigaDOS device, even volumes and assigned names, from the remote site
  298. by using the direct path to it.
  299.  
  300. An example:  To access the Amiga's parallel port from the remote site,
  301. just use the path REM::PAR:\\.  This is quite useful for using the
  302. print-to-file capabilities of some of the Psion applications.
  303.  
  304. Character conversion mode
  305. =========================
  306.  
  307. Since the Psion's operating system uses a different character codeset
  308. than the Amiga does, you normally can't easily exchange ASCII files
  309. between the two machines.  The AmigaNCP File Server however provides a
  310. special conversion mode which allows to convert files on the fly.
  311.  
  312. Whenever you add the special extension .CV to any remote file name,
  313. all characters read from or written to that file will
  314. automatically be converted by AmigaNCP.  The conversion is fully
  315. transparent to your applications.
  316.  
  317. An example:  To edit the Amiga text file HD1:Test/Test.TXT on the S3
  318. with automatic character conversion, use the virtual file name
  319. REM::HD1:\\TEST\\TEST.TXT.CV.
  320.  
  321. Note that character conversion mode should be used only for text
  322. files.  The S3 and S3a Word file format for example contains binary
  323. data which will be gracefully mangled if accessed in conversion mode.
  324.  
  325. File Server Options
  326. ===================
  327.  
  328. The AmigaNCP File Server may be started either from the shell or from
  329. Workbench.  To terminate the server, just start it again, it will put
  330. up a requester showing you the number of files in use and asking you
  331. whether you really want to quit.
  332.  
  333. The File Server accepts several options to modify the way it operates.
  334. Note that you have to set up ncp.library first (See Using AmigaNCP.).
  335.  
  336. Options may be given on the command line (shell) or using tooltype
  337. entries (Workbench).  You may use project icons to start the File
  338. Server in order to have different configurations at hand.
  339.  
  340. The option template is IBM=CHARSETCONV/S, SHOWICONS=SHOWINFO/S,
  341. HIDEEMPTYDRIVES/S, BUFFER=BUFFERSIZE.  You may enter ? to get
  342. additional help at the command line.
  343.  
  344. CharSetConv
  345. -----------
  346.  
  347. When the remote file system requests a directory scan, the file server
  348. examines each file to determine whether it is a text file or not(2).
  349. Text files are then returned both with their normal name and with the
  350. magic extension .CV added.
  351.  
  352. ShowInfo
  353. --------
  354.  
  355. Show *.info and .backdrop files during a directory scan.  You
  356. normally shouldn't set this option, the Psion has no use for these
  357. files and directory scans are much faster without them.
  358.  
  359. Please note that the Psion's Delete Whole Directory function will
  360. only work correctly on Amiga directories if ShowInfo has been enabled.
  361.  
  362. HideEmptyDrives
  363. ---------------
  364.  
  365. Upon a device list query, don't return drives which currently do not
  366. contain a medium.  This option is intended mainly to overcome an
  367. annoying quirk in the S3 and S3a system screen which resets the current
  368. device to LOC::\\M\\ each time a device reports E_NOT_READY.  This
  369. normally always happens when getting to REM::DF0: with no disk in the
  370. drive.
  371.  
  372. Note that, although these devices are not visible in the device list,
  373. they may as usual be accessed by manually entering the device name.
  374.  
  375. BufferSize
  376. ----------
  377.  
  378. Set the size of the filehandle buffers used by the File Server.  This
  379. parameter defaults to 4096 Bytes and normally doesn't need to be
  380. changed(3).
  381.  
  382. ---------- Footnotes ----------
  383.  
  384. (1)  Tech info:  Any device which responds positively to
  385. ACTION_IS_FILESYSTEM is considered to be a real file system.
  386.  
  387. (2)  Tech info:  This is done by reading the first 512 Bytes and
  388. scanning them for non-printable characters.  Files with the S
  389. protection bit set are always assumed to be text files.
  390.  
  391. (3)  This option has no effect on AmigaOS below version 3.1
  392.  
  393. AmigaNCP File System
  394. ********************
  395.  
  396. Introducing the File System
  397. ===========================
  398.  
  399. The AmigaNCP File System is an NCP application which provides access
  400. from the AmigaDOS environment to files on the remote machine.  It
  401. creates a new AmigaDOS device named NCP:, which in turn contains all
  402. remote devices as subdirectories.
  403.  
  404. The Amiga directory NCP:A refers to the device A: on the remote
  405. side, NCP:M refers to M: and so on.
  406.  
  407. If you want to access any file on the remote device, just add the full
  408. path name.  To access the file A:\\WRD\\SECRET.WRD, just use the
  409. Amiga file name NCP:A/WRD/SECRET.WRD.
  410.  
  411. You can access the new device from any Amiga application, including
  412. Workbench and your favourite directory tool, as if they were standard
  413. Amiga files.
  414.  
  415. On startup, the AmigaNCP File System immediately attempts to connect to
  416. the File Server on the remote machine.  If no connection can be made,
  417. the File System will refuse to start.  You may attempt to quit it at
  418. any time by starting it again, however, due to AmigaDOS constraints it
  419. will refuse to quit if there are any files or locks still in use.
  420.  
  421. Character Conversion Mode
  422. =========================
  423.  
  424. The AmigaNCP File System also features the character conversion mode.
  425. If you enable this option, all remote devices will be mirrored as
  426. CONV_<devname>, and all characters read from or written to files
  427. within these subdirectories will automatically be converted.
  428.  
  429. Example:  To access A:\\WRD\\SECRET.TXT with character conversion,
  430. use the file name NCP:CONV_A/WRD/SECRET.TXT.
  431.  
  432. The translation is fully transparent; you may, for example, use your
  433. favourite text editor to load a text file from the Psion, edit it and
  434. save it again.  Upon reading, it will be converted to the Amiga ISO
  435. character set, upon writing, it will be converted back to the IBM codes
  436. used by the Psion.
  437.  
  438. File System Options
  439. ===================
  440.  
  441. The File System accepts several options to modify the way it operates.
  442. Note that you have to set up ncp.library first (See Using AmigaNCP.).
  443.  
  444. Upon shell startup, options are specified on the command line.  The
  445. template is VOL=VOLUMENAME/K, DEV=DEVICENAME/K, SR=SHAREDREAD/S,
  446. IBM=CHARSETCONV/S, HED=HIDEEMPTYDRIVES/S, DWMS=DONTWARNMISSINGSERVER/S,
  447. ARR=AUTOREREAD/S: .  You may enter ? to get additional help at the
  448. command line.
  449.  
  450. If started from Workbench, the File System application will read its
  451. icon and parse the tooltypes for the same option keywords.  You may use
  452. project icons for starting the File System in order to have different
  453. configurations at hand.
  454.  
  455. VolumeName
  456. ----------
  457.  
  458. This options allows you to set the volume node name of the File System.
  459. Defaults to AmigaNCP-Remote.  This is the name the Workbench shows
  460. below the disk icon.
  461.  
  462. DeviceName
  463. ----------
  464.  
  465. Modifies the device name of the File System.  Defaults to NCP:.
  466.  
  467. SharedRead
  468. ----------
  469.  
  470. For historical reasons, there is no real read only mode in the
  471. AmigaDOS.  The access mode MODE_OLDFILE can be used for reading and
  472. writing an existing file from multiple accessors.  So an Amiga file
  473. system cannot predict whether a file opened with MODE_OLDFILE will
  474. also be written to.
  475.  
  476. The Psion filing system however limits multiple file access to read
  477. only mode.
  478.  
  479. To be as compatible as possible with existing Amiga applications, the
  480. AmigaNCP File System by default translates MODE_OLDFILE to exclusive
  481. read/write access on the Psion.
  482.  
  483. This may cause problems if a file is already opened for reading from
  484. the Psion side, perhaps because you have a Psion application running
  485. which accesses this file.  Even a read only access from the Amiga side
  486. will fail because it translates to a read/write access on the Psion
  487. side.
  488.  
  489. In order to overcome this AmigaDOS quirk, the AmigaNCP File System
  490. provides this option to translate MODE_OLDFILE to a shared read
  491. access on the Psion side.  Every write attempt on such a file will
  492. result in a ERROR_WRITE_PROTECTED.
  493.  
  494. CharSetConv
  495. -----------
  496.  
  497. Activate character conversion mode.  All Psion devices are mirrored as
  498. CONV_<devname and read/write accesses to files within these drawers
  499. are silently translated.
  500.  
  501. Note that file handles opened in character conversion mode don't
  502. support ACTION_SEEK.  This may cause problems with some applications.
  503.  
  504. HideEmptyDrives
  505. ---------------
  506.  
  507. Don't create subdirectories for Psion devices which don't contain a
  508. medium.
  509.  
  510. DontWarnMissingServer
  511. ---------------------
  512.  
  513. The File Server should normally be started first, because the Psion
  514. LINK application attempts to contact it as soon as the connection has
  515. been established, and it will not try again if no connection could be
  516. made.
  517.  
  518. Therefore, the File System will warn you with a requester if it can't
  519. detect the AmigaNCP File Server when it is started.  Setting this option
  520. instructs the File System not to do so.
  521.  
  522. AutoReRead
  523. ----------
  524.  
  525. By default, the File System reads the remote device list only once at
  526. the time it is started.
  527.  
  528. This should normally be no problem, unless you use HideEmptyDrives
  529. and replace SSD cartridges while a connection is active.
  530.  
  531. You can use DiskChange NCP: at any time to manually force the File
  532. System to read the device list again.  Or you can set AutoReRead,
  533. which causes the File System to read the device list from the remote
  534. side upon every access, which of course will slow accesses down a bit.
  535.  
  536. Implementation Details
  537. ======================
  538.  
  539. The AmigaNCP File System supports the following AmigaDOS packet types:
  540.  
  541.    * ACTION_IS_FILESYSTEM
  542.  
  543.    * ACTION_FLUSH
  544.  
  545.    * ACTION_DISK_INFO
  546.  
  547.    * ACTION_INFO
  548.  
  549.    * ACTION_COPY_DIR
  550.  
  551.    * ACTION_COPY_DIR_FH
  552.  
  553.    * ACTION_LOCATE_OBJECT
  554.  
  555.    * ACTION_FREE_LOCK
  556.  
  557.    * ACTION_EXAMINE_FH
  558.  
  559.    * ACTION_EXAMINE_OBJECT
  560.  
  561.    * ACTION_EXAMINE_NEXT
  562.  
  563.    * ACTION_CURRENT_VOLUME
  564.  
  565.    * ACTION_SAME_LOCK
  566.  
  567.    * ACTION_CREATE_DIR
  568.  
  569.    * ACTION_PARENT
  570.  
  571.    * ACTION_PARENT_FH
  572.  
  573.    * ACTION_DELETE_OBJECT
  574.  
  575.    * ACTION_RENAME_OBJECT
  576.  
  577.    * ACTION_DIE
  578.  
  579.    * ACTION_FINDINPUT
  580.  
  581.    * ACTION_FINDOUTPUT
  582.  
  583.    * ACTION_FINDUPDATE
  584.  
  585.    * ACTION_INHIBIT
  586.  
  587.    * ACTION_END
  588.  
  589.    * ACTION_READ
  590.  
  591.    * ACTION_WRITE
  592.  
  593.    * ACTION_SEEK
  594.  
  595.    * ACTION_SET_PROTECT
  596.  
  597.    * ACTION_SET_DATE
  598.  
  599. Other Tools
  600. ***********
  601.  
  602. The AmigaNCP package contains a few more programs which are meant for
  603. the advanced user.  Since they are also good examples for how to access
  604. the ncp.library, the source code for most of these utilities can be
  605. found in the Developer/Source/ drawer.
  606.  
  607. AmigaNCP-Monitor
  608. ================
  609.  
  610. The AmigaNCP-Monitor is a utility for monitoring the current network
  611. activity.  It displays an overview over the eight avaible NCP channels,
  612. their users, current connection states and the amount of data that has
  613. been transferred.
  614.  
  615.     AmigaNCP-Monitor may be started either from the shell or from
  616. Workbench.  There are no additional parameters.  The window position
  617. will be saved as a tooltype entry.
  618.  
  619. The Monitor opens a single window on the workbench screen.  The top
  620. part displays the states of the eight network channels, the bottom part
  621. shows overall statistics and whether NCP is currently connected.
  622.  
  623. ThisProc
  624.      The network name of the Amiga process using the channel.  The
  625.      first channel is always allocated by the LINK application.
  626.  
  627. RemotePr
  628.      The name of the remote process.  This may be empty, meaning the
  629.      channel is currently not connected.
  630.  
  631.          UnknClnt identifies a passive channel connected to an
  632.      unknown client.
  633.  
  634.      For the first channel, this may be either ARemLink, denoting
  635.      that the current connection has been initiated by the remote link,
  636.      or PRemLink, if the current connection was opened on behalf of
  637.      the ncp.library.
  638.  
  639. Status
  640.      This flag array denotes various internal states of
  641.      ncp.library.
  642.  
  643. Bytes Sent
  644.      How many bytes have been sent through this channel?
  645.  
  646. Bytes Received
  647.      How many bytes have been received through this channel?
  648.  
  649. Online since
  650.      The time on which ncp.library was started first.  The startup
  651.      time is used by the NCP protocol to determine whether a broken
  652.      connection can be reestablished or not.
  653.  
  654. Remote NCP
  655.      The remote NCP's startup time.
  656.  
  657. Version
  658.      The remote NCP's version.  This is generally 2 for AmigaNCP and
  659.      the Psion S3 and 3 for the S3a.
  660.  
  661. Connected
  662.      This will be displayed whenever there is an active connection to
  663.      any remote NCP.
  664.  
  665. S3PrintServer
  666. =============
  667.  
  668. The S3PrintServer is a small utility which allows you to print from
  669. your Psion directly to a printer connected to the Amiga.  It uses the
  670. Psion's capability to print to a serial printer, and simply passes any
  671. data from the serial port directly to the printer device via raw writes.
  672.  
  673. You have to turn off the Remote Link on the Psion side and terminate
  674. any NCP application running on the Amiga side before starting the
  675. S3PrintServer.  If you forget to turn off the Remote Link, junk will
  676. be printed due to misinterpreted NCP packets!
  677.  
  678. You must also set your Psion's printer configuration to serial
  679. printing, with the same baud rate used for NCP connections, turn off
  680. Xon/Xoff and turn on RTS/CTS and DSR/DTR handshaking.  The
  681. S3PrintServer itself reads the serial configuration from the file
  682. ENV:NCP.config.
  683.  
  684. The S3PrintServer uses the raw write capabilities of the
  685. printer.device and therefore ignores any printer driver settings.
  686. However, it respects your choice on which device to print, and even
  687. allows printing via network printer services, e.g.  Envoy Network
  688. Printing.
  689.  
  690. Therefore, you must select the correct WDR printer driver on the
  691. Psion.  This can be done in the Printer Setup dialog of the
  692. Word application.
  693.  
  694. Having done all this, you can print from your Psion applications simply
  695. by selecting the Print... menu, just as if the printer was connected
  696. directly to the Psion.
  697.  
  698. S3Run
  699. =====
  700.  
  701. The S3Run utility uses the LINK application's capability to launch
  702. a process on the remote side.  It's a shell only program which takes
  703. one or two parameters: S3Run filename commandline
  704.  
  705. The first argument denotes the file name of the remote program to run,
  706. for example TEST.IMG.  Due to NCP restrictions, this may only be a
  707. program on the Psion's top level directory or ROM.
  708.  
  709. The second argument may contain the command line to be passed to the
  710. created process.  This argument may be omitted, in which case no command
  711. line will be passed.
  712.  
  713. You may use \\xx escaping to insert the hexadecimal code xx into
  714. the command line.  See `the Psion SIBO SDK Manual' for more information
  715. on S3 command lines.
  716.  
  717. ncp.library API
  718. ***************
  719.  
  720. This part of the AmigaNCP documentation describes the use of AmigaNCP
  721. services within custom applications.  It assumes a broad knowledge of
  722. programming AmigaOS.
  723.  
  724. NCP Implementation
  725. ==================
  726.  
  727. The Psion NCP network protocol consists of four layers:
  728.  
  729. Serial Layer
  730.      A simple asynchronous serial 8/N/1 connection.  This is in fact
  731.      the hardware serial connection built into the 3-Link.
  732.  
  733. Packet Layer
  734.      A packet protocol providing checksums and multiple
  735.      retransmissions.  It is called LLMAC and somewhat based on the
  736.      MNP type protocols.
  737.  
  738. NCP Layer
  739.      NCP provides up to eight independant data streams between local
  740.      and remote processes.  Under the Psion OS, a process may use only
  741.      one NCP channel at a time.
  742.  
  743. Application Layer
  744.      Applications built on top of the NCP data stream service.  This
  745.      includes the remote file system and remote file server.  There is
  746.      also a supervisory application called LINK which controls the
  747.      server setup.
  748.  
  749. A more detailed description of NCP usage from the Psion side can be
  750. found in the `Psion SIBO SDK Manual, I/O Devices Reference'.
  751.  
  752. On the Amiga side, the serial layer is provided through any standard
  753. EXEC serial device, normally this will be the internal port's
  754. serial.device.  The packet and NCP layers have been built into
  755. the ncp.library.
  756.  
  757. Besides these basic layers, also the supervisory LINK application
  758. resides in the ncp.library.
  759.  
  760. All network services are accessible via function calls to the
  761. ncp.library.  In order to use these functions, you have to open
  762. the ncp.library first:
  763.  
  764.          #include <libraries/ncp.h>
  765.      
  766.          struct Library *NCPBase;
  767.          NCPBase = OpenLibrary( "ncp.library", NCP_VERSION );
  768.          if( !NCPBase )
  769.              fail_app();
  770.  
  771. If you are using SAS/C 6.50 or above, you may want to use the link
  772. library ncp.lib provided in the development toolkit.  It contains a
  773. constructor/destructor pair that automatically opens/closes the
  774. ncp.library upon startup/termination of your application.
  775.  
  776. If you are not using C, you'll have to build your own language specific
  777. glue definitions.  A function description file
  778. (Developer/FD/ncp_lib.fd) has been included.  The AmigaNCP
  779. programming interface doesn't use any fancy data structures, so you
  780. should have no problems with other programming languages.
  781.  
  782. The NCP network services are based on channels.  A channel is a
  783. connection between a local and a remote processes.  In the Psion EPOC
  784. environment, a channel is bound to a single process and bears the name
  785. of that process.  AmigaNCP allows you to specify arbitrary names for
  786. your channels, along with having multiple channels within a single
  787. application, if you wish to do so.
  788.  
  789. A channel may be opened in either active or passive mode.  An
  790. active channel attempts to connect to a remote process with a given name
  791. and refuses to open if the remote process doesn't exists or already is
  792. busy with some other connection.  A passive channel just sits around
  793. awaiting a connection from the remote site.  Passive channels are
  794. normally used for server applications awaiting connections from their
  795. clients, whereas active channels are used by clients to contact their
  796. server application.
  797.  
  798. I/O via NCP is done either synchronously or asynchronously.  The
  799. I/O interface of the ncp.library is quite similar to the EXEC device
  800. I/O interface.  See the function descriptions of the NCP I/O functions
  801. for more details.
  802.  
  803. The Developer/Source/ drawer provides some examples to show the use
  804. of the ncp.library calls.
  805.  
  806. Function Reference
  807. ==================
  808.  
  809. Note that this function reference is also available in standard Amiga
  810. Autodoc format (Developer/Autodocs/ncp.doc).
  811.  
  812. NCP_CloseChannel
  813. ----------------
  814.  
  815.         NAME
  816.          NCP_CloseChannel -- close a NCP channel
  817.      
  818.         SYNOPSIS
  819.          NCP_CloseChannel( channel )
  820.                             A0
  821.      
  822.         void NCP_CloseChannel( APTR );
  823.      
  824.         FUNCTION
  825.          Close a NCP channel previously opened by NCP_OpenChannel().
  826.          If this is an active link to the remote machine, it will be
  827.          closed.
  828.      
  829.         INPUTS
  830.          channel -- channel to close. May be NULL, in which case
  831.                     this functions does nothing.
  832.      
  833.         RESULT
  834.          None.
  835.      
  836.         EXAMPLE
  837.      
  838.         NOTES
  839.          An active NCP connection will be dropped about 10s
  840.          after the last channel has been closed.
  841.      
  842.         BUGS
  843.          None known.
  844.      
  845.         SEE ALSO
  846.          NCP_OpenChannel()
  847.  
  848. NCP_OpenChannel
  849. ---------------
  850.  
  851.         NAME
  852.          NCP_OpenChannel -- open a NCP channel to attempt to connect to
  853.                            the remote.
  854.      
  855.         SYNOPSIS
  856.          channel = NCP_OpenChannel( localname, remotename, flags )
  857.            D0                          A0          A1        D0
  858.      
  859.          APTR NCP_OpenChannel( STRPTR, STRPTR, ULONG );
  860.      
  861.         FUNCTION
  862.          Opens an NCP channel. If remotename is not NULL, attempts
  863.          to connect to the remote process and fails with a NULL
  864.          return if the connection could not be made. If remotename
  865.          is NULL, creates a passive channel silently awaiting remote
  866.          connection.
  867.      
  868.         INPUTS
  869.          localname -- name of local "process"
  870.          remotename -- either NULL for a passive channel or
  871.                        the remote process name which to connect
  872.                        to
  873.          flags -- currently unused, leave at 0
  874.      
  875.         RESULT
  876.          channel -- pointer to a channel object. NULL in case of
  877.                     an error, whereas additional error information
  878.                     can be found in IoErr()
  879.      
  880.         EXAMPLE
  881.          To connect to the remote file server:
  882.      
  883.             APTR channel;
  884.             channel = NCP_OpenChannel( "TestHost", "SYS$RFSV.*", 0 );
  885.      
  886.      
  887.         NOTES
  888.          Opening an active channel will result in an attempt to
  889.          create an NCP connection and fail upon any error (including
  890.          serial failure or inexistance of the remote process).
  891.          Creating an passive channel will not cause an NCP connection
  892.          attempt; this is done upon the first I/O request made to
  893.          channel.
  894.      
  895.         BUGS
  896.          None known.
  897.      
  898.         SEE ALSO
  899.          NCP_CloseChannel()
  900.  
  901. NCP_Read
  902. --------
  903.  
  904.         NAME
  905.          NCP_Read -- do a read request.
  906.      
  907.         SYNOPSIS
  908.          status = NCP_Read( channel, data, datasize )
  909.            D0                     A0
  910.      
  911.          LONG NCP_Read( APTR, APTR, ULONG );
  912.      
  913.         FUNCTION
  914.          This is basically identical to calling NCP_BeginRead()
  915.          followed by NCP_WaitRead().
  916.      
  917.         INPUTS
  918.          channel -- a NCP channel created by NCP_OpenChannel()
  919.          data -- receive buffer
  920.          datasize -- receive buffer size
  921.      
  922.         RESULT
  923.          status -- number of bytes read or a negative error
  924.                    number.
  925.      
  926.         EXAMPLE
  927.      
  928.         NOTES
  929.      
  930.         BUGS
  931.      
  932.         SEE ALSO
  933.          NCP_WaitRead(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()
  934.  
  935. NCP_BeginRead
  936. -------------
  937.  
  938.         NAME
  939.          NCP_BeginRead -- start a read request on the NCP channel.
  940.      
  941.         SYNOPSIS
  942.          error = NCP_BeginRead( channel, data, datasize )
  943.            D0                     A0      A1       D0
  944.      
  945.          LONG NCP_BeginRead( APTR, APTR, ULON G);
  946.      
  947.         FUNCTION
  948.          Queues a read operation on the current NCP channel.
  949.      
  950.         INPUTS
  951.          channel -- a NCP channel created by NCP_OpenChannel()
  952.          data -- receive buffer
  953.          datasize -- receive buffer size
  954.      
  955.         RESULT
  956.          error -- either 0 if the read was queued successfully
  957.                   or a negative error number
  958.      
  959.         EXAMPLE
  960.      
  961.         NOTES
  962.          Only one read request may be queued at a time on a single
  963.          channel. This function fails with NCPE_INUSE if there is
  964.          already a read request outstanding.
  965.      
  966.         BUGS
  967.          None known.
  968.      
  969.         SEE ALSO
  970.          NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_CheckRead()
  971.  
  972. NCP_AbortRead
  973. -------------
  974.  
  975.         NAME
  976.          NCP_AbortRead -- abort read currently in progress
  977.      
  978.         SYNOPSIS
  979.          NCP_AbortRead( channel )
  980.                           A0
  981.      
  982.          void NCP_AbortRead( APTR )
  983.      
  984.         FUNCTION
  985.          Aborts the current read request on the given NCP channel.
  986.          Does nothing if no read is pending.
  987.      
  988.         INPUTS
  989.          channel -- a NCP channel created by NCP_OpenChannel()
  990.      
  991.         RESULT
  992.          None.
  993.      
  994.         EXAMPLE
  995.      
  996.         NOTES
  997.          Never forget to finish a read request using NCP_WaitRead(),
  998.          or you'll end up in OS hell.
  999.      
  1000.         BUGS
  1001.          None known.
  1002.      
  1003.         SEE ALSO
  1004.          NCP_Read(), NCP_WaitRead(), NCP_CheckRead(), NCP_BeginRead()
  1005.  
  1006. NCP_CheckRead
  1007. -------------
  1008.  
  1009.         NAME
  1010.          NCP_CheckRead -- check if a read request is still pending
  1011.      
  1012.         SYNOPSIS
  1013.          status = NCP_CheckRead( channel )
  1014.            D0                       A0
  1015.      
  1016.          LONG NCP_CheckRead( APTR )
  1017.      
  1018.         FUNCTION
  1019.          Check if a read request is still pending on the given NCP
  1020.          channel.
  1021.      
  1022.         INPUTS
  1023.          channel -- a NCP channel created by NCP_OpenChannel()
  1024.      
  1025.         RESULT
  1026.          status -- FALSE if a read is currently pending,
  1027.                    TRUE if no request is pending or the current
  1028.                    request has completed.
  1029.      
  1030.         EXAMPLE
  1031.      
  1032.         NOTES
  1033.          Never forget to finish a read request using NCP_WaitRead(),
  1034.          or you'll end up in OS hell.
  1035.      
  1036.         BUGS
  1037.          None known.
  1038.      
  1039.         SEE ALSO
  1040.          NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_BeginRead()
  1041.  
  1042. NCP_WaitRead
  1043. ------------
  1044.  
  1045.         NAME
  1046.          NCP_WaitRead -- complete a read request on the NCP channel.
  1047.      
  1048.         SYNOPSIS
  1049.          result = NCP_WaitRead( channel )
  1050.            D0                     A0
  1051.      
  1052.          LONG NCP_WaitRead( APTR );
  1053.      
  1054.         FUNCTION
  1055.          Waits for the current read request to finish and
  1056.          returns the result.
  1057.      
  1058.         INPUTS
  1059.          channel -- a NCP channel created by NCP_OpenChannel()
  1060.      
  1061.         RESULT
  1062.          status -- number of bytes read or a negative error
  1063.                    number.
  1064.      
  1065.         EXAMPLE
  1066.      
  1067.         NOTES
  1068.          Every read request startet with NCP_BeginRead() absolutely
  1069.          must be followed by a NCP_WaitRead(), even if it already
  1070.          finished or was aborted via NCP_AbortRead().
  1071.      
  1072.         BUGS
  1073.          Calling this function without an queued read request
  1074.          will hang up your process.
  1075.      
  1076.         SEE ALSO
  1077.          NCP_Read(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()
  1078.  
  1079. NCP_ReadSig
  1080. -----------
  1081.  
  1082.         NAME
  1083.          NCP_ReadSig -- return signal mask of channel read port.
  1084.      
  1085.         SYNOPSIS
  1086.          sigmask = NCP_ReadSig( channel )
  1087.            D0                     A0
  1088.      
  1089.          ULONG NCP_ReadSig( APTR );
  1090.      
  1091.         FUNCTION
  1092.          This function returns the signal mask of the read port
  1093.          of the given NCP channel. This signal is set if a read
  1094.          request completes.
  1095.      
  1096.         INPUTS
  1097.          channel -- a NCP channel created by NCP_OpenChannel()
  1098.      
  1099.         RESULT
  1100.          sigmask -- signal mask of read port.
  1101.      
  1102.         EXAMPLE
  1103.      
  1104.         NOTES
  1105.          Note that this function returns a signal mask, not a signal bit number.
  1106.      
  1107.         BUGS
  1108.      
  1109.         SEE ALSO
  1110.          NCP_BeginRead()
  1111.  
  1112. NCP_Write
  1113. ---------
  1114.  
  1115.         NAME
  1116.          NCP_Write -- do a write request.
  1117.      
  1118.         SYNOPSIS
  1119.          status = NCP_Write( channel, data, datasize )
  1120.            D0                   A0     A1      D0
  1121.      
  1122.          LONG NCP_Write( APTR, APTR, ULONG );
  1123.      
  1124.         FUNCTION
  1125.          This is basically identical to calling NCP_BeginWrite()
  1126.          followed by NCP_WaitWrite().
  1127.      
  1128.         INPUTS
  1129.          channel -- a NCP channel created by NCP_OpenChannel()
  1130.          data -- receive buffer
  1131.          datasize -- receive buffer size
  1132.      
  1133.         RESULT
  1134.          status -- number of bytes written or a negative error
  1135.                    number.
  1136.      
  1137.         EXAMPLE
  1138.      
  1139.         NOTES
  1140.      
  1141.         BUGS
  1142.      
  1143.         SEE ALSO
  1144.          NCP_WaitWrite(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1145.  
  1146. NCP_BeginWrite
  1147. --------------
  1148.  
  1149.         NAME
  1150.          NCP_BeginWrite -- start a write request on the NCP channel.
  1151.      
  1152.         SYNOPSIS
  1153.          error = NCP_BeginWrite( channel, data, datasize )
  1154.            D0                     A0      A1       D0
  1155.      
  1156.          LONG NCP_BeginWrite( APTR, APTR, ULON G);
  1157.      
  1158.         FUNCTION
  1159.          Queues a write operation on the current NCP channel.
  1160.      
  1161.         INPUTS
  1162.          channel -- a NCP channel created by NCP_OpenChannel()
  1163.          data -- data buffer
  1164.          datasize -- data buffer size
  1165.      
  1166.         RESULT
  1167.          error -- either 0 if the write was queued successfully
  1168.                   or a negative error number
  1169.      
  1170.         EXAMPLE
  1171.      
  1172.         NOTES
  1173.          Only one write request may be queued at a time on a single
  1174.          channel. This function fails with NCPE_INUSE if there is
  1175.          already a write request outstanding.
  1176.      
  1177.         BUGS
  1178.          None known.
  1179.      
  1180.         SEE ALSO
  1181.          NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1182.  
  1183. NCP_AbortWrite
  1184. --------------
  1185.  
  1186.         NAME
  1187.          NCP_AbortWrite -- abort write currently in progress
  1188.      
  1189.         SYNOPSIS
  1190.          NCP_AbortWrite( channel )
  1191.                           A0
  1192.      
  1193.          void NCP_AbortWrite( APTR )
  1194.      
  1195.         FUNCTION
  1196.          Aborts the current write request on the given NCP channel.
  1197.          Does nothing if no write is pending.
  1198.      
  1199.         INPUTS
  1200.          channel -- a NCP channel created by NCP_OpenChannel()
  1201.      
  1202.         RESULT
  1203.          None.
  1204.      
  1205.         EXAMPLE
  1206.      
  1207.         NOTES
  1208.          Never forget to finish a write request using NCP_WaitWrite(),
  1209.          or you'll end up in OS hell.
  1210.      
  1211.         BUGS
  1212.          None known.
  1213.      
  1214.         SEE ALSO
  1215.          NCP_Write(), NCP_WaitWrite(), NCP_CheckWrite(), NCP_BeginWrite()
  1216.  
  1217. NCP_CheckWrite
  1218. --------------
  1219.  
  1220.         NAME
  1221.          NCP_CheckWrite -- check if a write request is still pending
  1222.      
  1223.         SYNOPSIS
  1224.          status = NCP_CheckWrite( channel )
  1225.            D0                       A0
  1226.      
  1227.          LONG NCP_CheckWrite( APTR )
  1228.      
  1229.         FUNCTION
  1230.          Check if a write request is still pending on the given NCP
  1231.          channel.
  1232.      
  1233.         INPUTS
  1234.          channel -- a NCP channel created by NCP_OpenChannel()
  1235.      
  1236.         RESULT
  1237.          status -- FALSE if a write is currently pending,
  1238.                    TRUE if no request is pending or the current
  1239.                    request has completed.
  1240.      
  1241.         EXAMPLE
  1242.      
  1243.         NOTES
  1244.          Never forget to finish a write request using NCP_WaitWrite(),
  1245.          or you'll end up in OS hell.
  1246.      
  1247.         BUGS
  1248.          None known.
  1249.      
  1250.         SEE ALSO
  1251.          NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_BeginWrite()
  1252.  
  1253. NCP_WaitWrite
  1254. -------------
  1255.  
  1256.         NAME
  1257.          NCP_WaitWrite -- complete a write request on the NCP channel.
  1258.      
  1259.         SYNOPSIS
  1260.          result = NCP_WaitWrite( channel )
  1261.            D0                     A0
  1262.      
  1263.          LONG NCP_WaitWrite( APTR );
  1264.      
  1265.         FUNCTION
  1266.          Waits for the current write request to finish and
  1267.          returns the result.
  1268.      
  1269.         INPUTS
  1270.          channel -- a NCP channel created by NCP_OpenChannel()
  1271.      
  1272.         RESULT
  1273.          status -- number of bytes written or a negative error
  1274.                    number.
  1275.      
  1276.         EXAMPLE
  1277.      
  1278.         NOTES
  1279.          Every write request startet with NCP_BeginWrite() absolutely
  1280.          must be followed by a NCP_WaitWrite(), even if it already
  1281.          finished or was aborted via NCP_AbortWrite().
  1282.      
  1283.         BUGS
  1284.          Calling this function without an queued write request
  1285.          will hang up your process.
  1286.      
  1287.         SEE ALSO
  1288.          NCP_Write(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1289.  
  1290. NCP_WriteSig
  1291. ------------
  1292.  
  1293.         NAME
  1294.          NCP_WriteSig -- return signal mask of channel write port.
  1295.      
  1296.         SYNOPSIS
  1297.          sigmask = NCP_WriteSig( channel )
  1298.            D0                     A0
  1299.      
  1300.          ULONG NCP_WriteSig( APTR );
  1301.      
  1302.         FUNCTION
  1303.          This function returns the signal mask of the write port
  1304.          of the given NCP channel. This signal is set if a write
  1305.          request completes.
  1306.      
  1307.         INPUTS
  1308.          channel -- a NCP channel created by NCP_OpenChannel()
  1309.      
  1310.         RESULT
  1311.          sigmask -- signal mask of write port.
  1312.      
  1313.         EXAMPLE
  1314.      
  1315.         NOTES
  1316.          Note that this function returns a signal mask, not a signal bit number.
  1317.      
  1318.         BUGS
  1319.      
  1320.         SEE ALSO
  1321.          NCP_BeginWrite()
  1322.  
  1323. NCP_Fault
  1324. ---------
  1325.  
  1326.         NAME
  1327.          NCP_Fault -- return localized NCP error string
  1328.      
  1329.         SYNOPSIS
  1330.          NCP_Fault( code, header, buffer, buffersize );
  1331.                     D0     A0      A1        D1
  1332.      
  1333.         void NCP_Fault( LONG, STRPTR, STRPTR, ULONG );
  1334.      
  1335.         FUNCTION
  1336.          Returns a localized text string associated with the
  1337.          error code.
  1338.      
  1339.         INPUTS
  1340.          code -- NCP error code
  1341.          header -- header to insert before string. May be NULL
  1342.          buffer -- buffer to write the error text to
  1343.          buffersize -- size of buffer
  1344.      
  1345.         RESULT
  1346.          None.
  1347.      
  1348.         EXAMPLE
  1349.      
  1350.         NOTES
  1351.      
  1352.         BUGS
  1353.          None known.
  1354.      
  1355.         SEE ALSO
  1356.          dos.library/Fault()
  1357.  
  1358. NCP_LinkRemoteRun
  1359. -----------------
  1360.  
  1361.         NAME
  1362.          NCP_LinkRemoteRun -- use the NCP link channel to run a program on
  1363.                               the remote machine.
  1364.      
  1365.         SYNOPSIS
  1366.          error = NCP_LinkRemoteRun( filename, cmdline, cmdlinelen )
  1367.          D0                            A0       A1        D0
  1368.      
  1369.         LONG NCP_LinkRemoteRun( STRPTR, APTR, ULONG );
  1370.      
  1371.         FUNCTION
  1372.          Use the LINK supervisor channel to have the remote link
  1373.          run a program. No NCP channel needs to be opened in order
  1374.          to perform this operation.
  1375.      
  1376.         INPUTS
  1377.          filename -- file name of the remote program to start
  1378.          cmdline -- pointer to command line array. Note that
  1379.                     EPOC command lines are *NOT* zero terminated.
  1380.          cmdlinelen -- length of command line in bytes. May be
  1381.                        zero, in which case no command line
  1382.                        is transfered.
  1383.      
  1384.         RESULT
  1385.          error -- either an AmigaNCP specific error code or the
  1386.                   result code from the remote link.
  1387.      
  1388.         EXAMPLE
  1389.          Have WORD.APP read the Amiga startup sequence:
  1390.      
  1391.             UBYTE cmdline[] = {
  1392.              "OANCPTest\000 V TES\000REM::SYS:\S\STARTUP-SEQUENCE\000"
  1393.             };
  1394.             error = NCP_LinkRemoteRun( "WORD.APP", cmdline, sizeof( cmdline ) );
  1395.      
  1396.         NOTES
  1397.          See the Psion SDK for more information about using commandlines and
  1398.          the LINK process launch feature.
  1399.      
  1400.         BUGS
  1401.          None known.
  1402.      
  1403.         SEE ALSO
  1404.  
  1405. NCP_clnl
  1406. --------
  1407.  
  1408.         NAME
  1409.          NCP_clnl -- clear CR/LF at end of line.
  1410.      
  1411.         SYNOPSIS
  1412.          NCP_clnl( string )
  1413.                    A0
  1414.      
  1415.          void NCP_clnl( STRPTR );
  1416.      
  1417.         FUNCTION
  1418.          Clears any CR or LF characters at the end of the string.
  1419.      
  1420.         INPUTS
  1421.          string -- pointer to string (contents will be modified)
  1422.      
  1423.         RESULT
  1424.          None.
  1425.      
  1426.         EXAMPLE
  1427.      
  1428.         NOTES
  1429.      
  1430.         BUGS
  1431.          None known.
  1432.      
  1433.         SEE ALSO
  1434.  
  1435. NCP_ibm2iso
  1436. -----------
  1437.  
  1438.         NAME
  1439.          NCP_ibm2iso -- convert IBM to ISO charachter
  1440.      
  1441.         SYNOPSIS
  1442.          isochar = NCP_ibm2iso( ibmchar )
  1443.            D0                    D0 0:7
  1444.      
  1445.          UBYTE NCP_ibm2iso( UBYTE );
  1446.      
  1447.         FUNCTION
  1448.          Converts a character from the IBM to the ISO charset.
  1449.      
  1450.         INPUTS
  1451.          ibmchar -- character of the IBM codeset
  1452.      
  1453.         RESULT
  1454.          isochar -- equivalent character in the ISO codeset
  1455.      
  1456.         EXAMPLE
  1457.      
  1458.         NOTES
  1459.      
  1460.         BUGS
  1461.          None known.
  1462.      
  1463.         SEE ALSO
  1464.  
  1465. NCP_iso2ibm
  1466. -----------
  1467.  
  1468.         NAME
  1469.          NCP_iso2ibm -- convert IBM to ISO charachter
  1470.      
  1471.         SYNOPSIS
  1472.          ibmchar = NCP_iso2ibm( isochar )
  1473.            D0                    D0 0:7
  1474.      
  1475.          UBYTE NCP_iso2ibm( UBYTE );
  1476.      
  1477.         FUNCTION
  1478.          Converts a character from the ISO to the IBM charset.
  1479.      
  1480.         INPUTS
  1481.          isochar -- character of the ISO codeset
  1482.      
  1483.         RESULT
  1484.          ibmchar -- equivalent character in the IBM codeset
  1485.      
  1486.         EXAMPLE
  1487.      
  1488.         NOTES
  1489.      
  1490.         BUGS
  1491.          None known.
  1492.      
  1493.         SEE ALSO
  1494.  
  1495. NCP_IWORD
  1496. ---------
  1497.  
  1498.         NAME
  1499.          NCP_IWORD -- swap bytes in word
  1500.      
  1501.         SYNOPSIS
  1502.          sword = NCP_IWORD( word )
  1503.            D0                D0
  1504.      
  1505.          UWORD NCP_IWORD( UWORD );
  1506.      
  1507.         FUNCTION
  1508.          Swaps the byte order within the word.
  1509.      
  1510.         INPUTS
  1511.          word -- a 16 bit data word.
  1512.      
  1513.         RESULT
  1514.          sword -- the same word with the byte order swapped.
  1515.      
  1516.         EXAMPLE
  1517.      
  1518.         NOTES
  1519.      
  1520.         BUGS
  1521.          None known.
  1522.      
  1523.         SEE ALSO
  1524.  
  1525. NCP_IWORDP
  1526. ----------
  1527.  
  1528.         NAME
  1529.          NCP_IWORDP -- swap bytes in word (pointer version)
  1530.      
  1531.         SYNOPSIS
  1532.          sword = NCP_IWORDP( wordp1, wordp2 )
  1533.            D0                  A0      A1
  1534.      
  1535.          UWORD NCP_IWORDP( UWORD *, UWORD * );
  1536.      
  1537.         FUNCTION
  1538.          Swaps the byte order from the word pointed to by wordp1
  1539.          and places the result in the word pointed to by wordp2.
  1540.      
  1541.         INPUTS
  1542.          wordp1 -- pointer to source word
  1543.          wordp2 -- pointer to destination word
  1544.      
  1545.         RESULT
  1546.          sword -- the same word with the byte order swapped.
  1547.      
  1548.         EXAMPLE
  1549.      
  1550.         NOTES
  1551.          The words don't need to be word aligned.
  1552.      
  1553.         BUGS
  1554.          The 68020++ version of ncp.library requires the hardware
  1555.          to be able to do misaligned word accesses. Some early
  1556.          accelerator boards may have problems doing this.
  1557.      
  1558.         SEE ALSO
  1559.  
  1560. NCP_IWORDPI
  1561. -----------
  1562.  
  1563.         NAME
  1564.          NCP_IWORDPI -- swap bytes in word (in-place pointer version)
  1565.      
  1566.         SYNOPSIS
  1567.          sword = NCP_IWORDPI( wordp1 )
  1568.            D0                   A0
  1569.      
  1570.          UWORD NCP_IWORDP( UWORD * )
  1571.      
  1572.         FUNCTION
  1573.          Swaps the byte order within the word pointed to by wordp.
  1574.      
  1575.         INPUTS
  1576.          wordp -- pointer to word to swap
  1577.      
  1578.         RESULT
  1579.          sword -- the same word with the byte order swapped.
  1580.      
  1581.         EXAMPLE
  1582.      
  1583.         NOTES
  1584.          The word doesn't need to be word aligned.
  1585.      
  1586.         BUGS
  1587.          The 68020++ version of ncp.library requires the hardware
  1588.          to be able to do misaligned word accesses. Some early
  1589.          accelerator boards may have problems doing this.
  1590.      
  1591.         SEE ALSO
  1592.  
  1593. NCP_ILONG
  1594. ---------
  1595.  
  1596.         NAME
  1597.          NCP_ILONG -- swap bytes in longword
  1598.      
  1599.         SYNOPSIS
  1600.          slongword = NCP_ILONG( longword )
  1601.            D0                     D0
  1602.      
  1603.          ULONG NCP_ILONG( ULONG );
  1604.      
  1605.         FUNCTION
  1606.          Swaps the byte order within the longword.
  1607.      
  1608.         INPUTS
  1609.          longword -- a 32 bit data word.
  1610.      
  1611.         RESULT
  1612.          slongword -- the same word with the byte order swapped.
  1613.      
  1614.         EXAMPLE
  1615.      
  1616.         NOTES
  1617.      
  1618.         BUGS
  1619.          None known.
  1620.      
  1621.         SEE ALSO
  1622.  
  1623. NCP_ILONGP
  1624. ----------
  1625.  
  1626.         NAME
  1627.          NCP_ILONGP -- swap bytes in longword (pointer version)
  1628.      
  1629.         SYNOPSIS
  1630.          sword = NCP_ILONGP( longwordp1, longwordp2 )
  1631.            D0                    A0          A1
  1632.      
  1633.          ULONG NCP_ILONGP( ULONG *, ULONG * );
  1634.      
  1635.         FUNCTION
  1636.          Swaps the byte order from the longword pointed to by longwordp1
  1637.          and places the result in the longword pointed to by longwordp2.
  1638.      
  1639.         INPUTS
  1640.          longwordp1 -- pointer to source longword
  1641.          longwordp2 -- pointer to destination longword
  1642.      
  1643.         RESULT
  1644.          sword -- the same word with the byte order swapped.
  1645.      
  1646.         EXAMPLE
  1647.      
  1648.         NOTES
  1649.          The longwords don't need to be word aligned.
  1650.      
  1651.         BUGS
  1652.          The 68020++ version of ncp.library requires the hardware
  1653.          to be able to do misaligned word accesses. Some early
  1654.          accelerator boards may have problems doing this.
  1655.      
  1656.         SEE ALSO
  1657.  
  1658. NCP_ILONGPI
  1659. -----------
  1660.  
  1661.         NAME
  1662.          NCP_ILONGPI -- swap bytes in longword (in-place pointer version)
  1663.      
  1664.         SYNOPSIS
  1665.          sword = NCP_ILONGPI( longwordp )
  1666.            D0                    A0
  1667.      
  1668.          ULONG NCP_ILONGP( ULONG * )
  1669.      
  1670.         FUNCTION
  1671.          Swaps the byte order within the longword pointed to by longwordp.
  1672.      
  1673.         INPUTS
  1674.          longwordp -- pointer to longword to swap
  1675.      
  1676.         RESULT
  1677.          sword -- the same word with the byte order swapped.
  1678.      
  1679.         EXAMPLE
  1680.      
  1681.         NOTES
  1682.          The longword doesn't need to be word aligned.
  1683.      
  1684.         BUGS
  1685.          The 68020++ version of ncp.library requires the hardware
  1686.          to be able to do misaligned word accesses. Some early
  1687.          accelerator boards may have problems doing this.
  1688.      
  1689.         SEE ALSO
  1690.  
  1691. Error codes from NCP functions
  1692. ==============================
  1693.  
  1694. Several ncp.library functions may return negative error numbers.
  1695. Note that besides the errors internal to ncp.library, standard EPOC
  1696. OS errors may be returned by some functions.
  1697.  
  1698. NCPE_INUSE (-1)
  1699.      There is already a read/write request pending on the given channel.
  1700.  
  1701. NCPE_ABORTED (-2)
  1702.      The read/write request has been aborted by NCP_AbortXXX()
  1703.  
  1704. NCPE_OFFLINE (-3)
  1705.      There is no NCP connection.  This may denote that the remote NCP
  1706.      closed the connection.
  1707.  
  1708. NCPE_INACTIVE (-4)
  1709.      The channel is currently inactive.  Most likely it has been closed
  1710.      by the remote process, or the NCP connection is currently dropped
  1711.      due to serial link failure.
  1712.  
  1713. NCPE_NOTFOUND (-5)
  1714.      You attempted to open an active channel and the remote process
  1715.      didn't exist.
  1716.  
  1717. NCPE_RECONNECTED (-6)
  1718.      This is not really an error.  Queued read requests will be
  1719.      terminated with this error value if the NCP connection has been
  1720.      succesfully reconnected.
  1721.  
  1722. NCPE_NEWUSER (-7)
  1723.      This is not really an error.  It may come up if the remote client
  1724.      of a passive channel changed.
  1725.  
  1726. Index
  1727. *****
  1728.  
  1729.  
  1730.  
  1731.  NCP.config                             Using AmigaNCP
  1732.  AmigaNCP File Server                   File Server
  1733.  AmigaNCP File System                   File System
  1734.  API                                    API
  1735.  error codes                            Errors
  1736.  File Server options                    File Server
  1737.  File System Options                    File System
  1738.  function calls                         API
  1739.  Installation                           Using AmigaNCP
  1740.  Installing AmigaNCP                    Using AmigaNCP
  1741.  Introduction                           Introduction
  1742.  Monitor                                AmigaNCP-Monitor
  1743.  NCP errors                             Errors
  1744.  NCP-Monitor                            AmigaNCP-Monitor
  1745.  ncp.library calls                      API
  1746.  ncp.library functions                  API
  1747.  NCP_AbortRead                          NCP_AbortRead
  1748.  NCP_AbortWrite                         NCP_AbortWrite
  1749.  NCP_BeginRead                          NCP_BeginRead
  1750.  NCP_BeginWrite                         NCP_BeginWrite
  1751.  NCP_CheckRead                          NCP_CheckRead
  1752.  NCP_CheckWrite                         NCP_CheckWrite
  1753.  NCP_clnl                               NCP_clnl
  1754.  NCP_CloseChannel                       NCP_CloseChannel
  1755.  NCP_Fault                              NCP_Fault
  1756.  NCP_ibm2iso                            NCP_ibm2iso
  1757.  NCP_ILONG                              NCP_ILONG
  1758.  NCP_ILONGP                             NCP_ILONGP
  1759.  NCP_ILONGPI                            NCP_ILONGPI
  1760.  NCP_iso2ibm                            NCP_iso2ibm
  1761.  NCP_IWORD                              NCP_IWORD
  1762.  NCP_IWORDP                             NCP_IWORDP
  1763.  NCP_IWORDPI                            NCP_IWORDPI
  1764.  NCP_LinkRemoteRun                      NCP_LinkRemoteRun
  1765.  NCP_OpenChannel                        NCP_OpenChannel
  1766.  NCP_Read                               NCP_Read
  1767.  NCP_ReadSig                            NCP_ReadSig
  1768.  NCP_WaitRead                           NCP_WaitRead
  1769.  NCP_WaitWrite                          NCP_WaitWrite
  1770.  NCP_Write                              NCP_Write
  1771.  NCP_WriteSig                           NCP_WriteSig
  1772.  Network Monitor                        AmigaNCP-Monitor
  1773.  Options, File Server                   File Server
  1774.  Options, File System                   File System
  1775.  Other Tools                            Other Tools
  1776.  Parts                                  Introduction
  1777.  Remote File Server                     File Server
  1778.  Remote File System                     File System
  1779.  S3PrintServer                          S3PrintServer
  1780.  S3Run                                  S3Run
  1781.  serial configuration                   Using AmigaNCP
  1782.  serial.device, configuration of        Using AmigaNCP
  1783.  
  1784.